#!/bin/env python
# -*- coding: utf-8 -*-

#This file is part of pyLot library.
#
# pyLot is free software: you can redistribute it and/or modify
# it under the terms of the GNU Lesser General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# pyLot is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public License
# along with pyLot.  If not, see <http://www.gnu.org/licenses/>.

__author__ = u'Pierre Puiseux, Guillaume Baty'
__copyright__ = u"Copyright 2011-2012 (C) andheo, Université de Pau et des Pays de l'Adour"
__credits__ = [u'Pierre Puiseux', u'Guillaume Baty']
__license__ = "GNU Lesser General Public License"

u"""
Interfaces thread/process
"""

__all__ = [u'IIOHandler']

from traits.api import Interface

class IIOHandler (Interface):
  u"""
  Class used to write message to user.
  
  The purpose of this class is to easily change text outputs without writing
  code again. For example, if you write a script and display a text in 
  (using this class), you can use the same code in script, console and graphical
  user interface (GUI)

  Example

  In a python file, you write :
  display.write('Welcome', style='title')
  display.write('Hello world')

  The result will depend of the implementations

  * A console implementation can display ::

    Welcome
    =-=-=-=
    Hello world
  
  * A GUI implementation can display a big blue "Welcome" and a small 
  "Hello world" in a popup windows or in a text view ...
  
  There are THREE views :
  
    - textout (write method)
    - stdout (writeStdout method)
    - stderr (writeStderr method)
    
  Text is written to all writers defined in "view_writers" attributes
  If view_writers list is empty, text is lost.
  """

  def __init__ (self, stdout=None, stderr=None, status=None,
                display_level=u'standard'):
    """
    level : unicode

    List of ILogger : 

      - stdout_writers
      - stderr_writers
      - textout_writers
      - status_writers
  
    ILogger :
      - stdout
      - stderr
      - textout
      - status
    """

  def goodLevel (self, option_level):
    u"""
    Test display level using good_level function.

    Dictionnary used is :
      'silent':0, 'standard':1, 'verbose':5, 'debug':10
    Current level is defined by :
      ShellManager.io.level

    .. seealso ::

      :func:`~_pylot.minimal.good_level` function

    """
    pass

  def write (self, text, style=u'std', level=u'standard', writers=None):
    u"""
    write 'text' to user if 'level' matches manager current display level 
    Text format depend of style value. 
    Text is written in "text view" (also called default view).
    
    Available styles :

      - **std** : normal text, default
      - **title** : header/section title
      - **warn** : warning information
      - **info** : additionnal information, comments style
      
    Available levels :

      - **silent** : text always displayed. use this level only for very very important messages
      - **standard** : standard program output
      - **verbose** : additionnal optional messages
      - **debug** : messages useful for debug purposes only

    :param text: text you want to write
    :type text: str
    :param style: text style 
    :type style: str
    :param level: 'display level' of this text
    :type level: str
    :param writers: list of writers. If None (default) uses default IOHandler writers
    :type writers: list
    """
    pass

  def writeStatus (self, text, style=u'std', level=u'standard'):
    u"""
    Like :meth:`pylot.core.IIOHandler.write` but write in
    "status" view if available else in default view.
    A StatusBar is an example of status view
    """
    pass

  def writePopUp (self, text, title=None, style=u'std', level=u'standard'):
    u"""
    Like :meth:`pylot.core.IIOHandler.write` but write in
    a popup view if available else in default view.
    """
    pass

  def writeStdout (self, text, style=u'std', level=u'standard'):
    u"""
    Like :meth:`pylot.core.IIOHandler.write` but write in
    "stdout" view if available else in default view.
    """
    pass

  def writeStderr (self, text, style=u'std', level=u'standard'):
    u"""
    Like :meth:`pylot.core.IIOHandler.write` but write in
    "stderr" view if available else in default view.
    """
    pass

  def writeBoth (self, text, style=u'std', level=u'standard'):
    u"""
    Like :meth:`pylot.core.IIOHandler.write` but write in
    both "stdout" and "stderr" views if availables else in default view.
    
    .. warning ::
      writeBoth hasn't "writers" parameters ! 
    """
    pass

  def writeAll (self, text, style=u'std', level=u'standard'):
    pass

  def rawInput (self, text=u''):
    u"""
    Like standard python function :func:`raw_input`.
    """
    pass

  def yesNoQuestion(self, text=u''):
    pass

  def editData (self, data_obj, text=u''):
    u"""
    Edit internal state of object data_obj.
    Type supported : Container, Datum, Traits

    Only these three type are allowed to keep interface implementation 
    possible.
    """
    pass

  def resetToDefaultWriters (self):
    pass
